如何使用 VPage API

本指南将帮助您快速上手使用 VPage API。

基本使用

1. 监听页面初始化

在页面初始化时创建表单和操作按钮：

thisApp.pageOnInit = async (context) => {
  // 创建表单
  const formBuilder = context.addForm();
  
  const userFieldSet = formBuilder.addFieldSet({
    title: '用户信息',
    fieldsPerLine: 2
  });
  
  userFieldSet
    .addField({
      id: 'username',
      type: 'Text',
      title: '用户名',
      required: true
    })
    .addField({
      id: 'email',
      type: 'Text',
      title: '邮箱',
      required: true
    });
  
  // 添加操作按钮
  const actionBar = context.getActionBar();
  actionBar.addButton({
    id: 'submit',
    text: '提交',
    title: '点击提交表单数据',
    type: 'raised',
    onClick: (formExecutionContext) => {
      // 处理提交逻辑
      console.log('提交按钮被点击');
    }
  });
};

2. 监听页面激活

在页面被激活时更新标题或加载数据：

thisApp.pageOnActive = async (context) => {
  // 获取页面上下文
  const pageContext = context.getPageContext();
  
  // 更新页面标题
  pageContext.changeTitle('用户详情页面');
  
  // 获取查询参数
  const params = pageContext.getQueryParams();
  
  if (params.userId) {
    // 根据用户ID加载数据
    const result = await pageContext.graphql(`
      query {
        User(criteriaStr: "id = ${params.userId}") {
          id
          name
          email
        }
      }
    `);
    
    console.log('用户数据:', result);
  }
};

3. 监听页面取消激活

在页面失去焦点时保存状态：

thisApp.pageOnDeActive = (context) => {
  // 保存当前表单状态
  console.log('页面即将失去焦点，保存状态...');
  
  // 可以在这里执行清理操作
  // 例如：清除定时器、保存草稿等
};

高级用法

动态表单创建

根据查询参数动态创建表单：

thisApp.pageOnInit = async (context) => {
  const formBuilder = context.addForm();
  const pageContext = context.getPageContext();
  const params = pageContext.getQueryParams();
  
  // 添加基本信息字段集合
  const baseFieldSet = formBuilder.addFieldSet({
    title: '基本信息',
    fieldsPerLine: 2
  });
  
  if (params.mode === 'edit') {
    // 编辑模式
    baseFieldSet
      .addField({
        id: 'id', 
        type: 'Text',
        hidden: true
      })
      .addField({
        id: 'name',
        type: 'Text', 
        title: '名称'
      })
      .addField({
        id: 'description',
        type: 'TextArea', 
        title: '描述'
      });
  } else {
    // 查看模式
    baseFieldSet
      .addField({
        id: 'name',
        type: 'Text', 
        title: '名称',
        readonly: true
      })
      .addField({
        id: 'description',
        type: 'TextArea', 
        title: '描述',
        readonly: true
      });
  }
};

错误处理

在使用VPage API时，建议添加错误处理：

thisApp.pageOnActive = async (context) => {
  // 获取页面上下文
  const pageContext = context.getPageContext();
  
  try {
    const result = await pageContext.graphql(`
      query {
        users: User {
          id
          name
        }
      }
    `);
    
    console.log('用户列表:', result.users);
  } catch (error) {
    console.error('加载用户数据失败:', error);
    // 显示错误提示
  }
};

最佳实践

1. 分离关注点：将不同的事件处理逻辑分离到不同的函数中
2. 异步处理：对于数据加载等操作，使用async/await确保代码可读性
3. 错误处理：始终为异步操作添加错误处理
4. 性能优化：避免在pageOnInit中执行大量DOM操作